home *** CD-ROM | disk | FTP | other *** search
aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) NNNNAAAAMMMMEEEE alParams - Audio Library parameters DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN This manual page describes the semantics of Audio Library (AL) parameters. Parameters are the AL's mechanism for obtaining or setting the state of each software or hardware audio resource. Parameters are also used to set/unset audio event notification. Each type of AL resource accepts different parameters. This manual page is divided up into sections, each of which describes a resource type and the parameters it accepts. See aaaallllRRRReeeessssoooouuuurrrrcccceeeessss for a more thorough description of resources and their properties. For more information about actually setting and acquiring the values of parameters, see aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) and aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))). For more information on selecting and deselecting parameters for audio event notification, refer to aaaallllSSSSeeeelllleeeeccccttttEEEEvvvveeeennnnttttssss((((3333ddddmmmm)))) and aaaallllDDDDeeeesssseeeelllleeeeccccttttEEEEvvvveeeennnnttttssss((((3333ddddmmmm)))). PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS AAAANNNNDDDD VVVVAAAALLLLUUUUEEEESSSS Parameters are retrieved or set using an ALpv structure. The most important two fields in the ALpv are: typedef union { int param; /* the parameter */ ALvalue value; /* the associated value */ [...] } ALpv; The ALvalue structure is a union of three types: typedef union { int i; /* 32-bit integer values */ long long ll; /* 64-bit integer and fixed-point values */ void* ptr; /* pointer values */ } ALvalue; The AL supports a small number of data types, each of which uses a specific field of the ALvalue. These are: 32-bit integer Uses the value.i field. Resource Uses the value.i field. Enumeration Uses the value.i field. 64-bit integer Uses the value.ll field. PPPPaaaaggggeeee 1111 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) Fixed-point Uses the value.ll field. aaaallllFFFFiiiixxxxeeeeddddTTTTooooDDDDoooouuuubbbblllleeee((((3333ddddmmmm)))) and aaaallllDDDDoooouuuubbbblllleeeeTTTTooooFFFFiiiixxxxeeeedddd((((3333ddddmmmm)))) are convenience functions to convert between double-precision floating-point and 64-bit fixed-point. Vectors, Sets, Matrices, Strings The value.ptr field must point to the actual value. There are also required size fields for these data types. See aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) and aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for more information. In addition, some parameters may support only some subset of aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))), aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))), aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))), aaaallllSSSSeeeelllleeeeccccttttEEEEvvvveeeennnnttttssss((((3333ddddmmmm)))) and aaaallllDDDDeeeesssseeeelllleeeeccccttttEEEEvvvveeeennnnttttssss((((3333ddddmmmm)))). Also, unless otherwise stated, event data information should be retrieved with aaaallllGGGGeeeettttEEEEvvvveeeennnnttttVVVVaaaalllluuuueeee((((3333ddddmmmm)))). UUUUNNNNIIIIVVVVEEEERRRRSSSSAAAALLLL PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS The following parameters apply to all resources. AL_TYPE (32-bit integer, get only) The type of the resource. All resources have types. Some types are subtypes of another; in this case, parameters which apply to the supertype also apply to the subtype. See the aaaallllIIIIssssSSSSuuuubbbbttttyyyyppppeeee((((3333ddddmmmm)))) manual page for more information. AL_NAME (character string, get only) The name of the resource. This name is typically used internally in applications, for example, for saving parameters to files. It can be passed into aaaallllGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeeeBBBByyyyNNNNaaaammmmeeee((((3333ddddmmmm)))) to retrieve the original resource. It is constant and unique for a given resource on a given system. AL_LABEL (character string, get/set/events) The label of the resource. This is a human-readable description of the resource. Use this, for example, for resource selection in menus, or for otherwise displaying resources to users. It is unique on a given system. It is also user-configurable. Attempts to set its value to equal an existing label on the same subsystem will be rejected. If the same label exists on another subsystem, the system will render them unique by prepending the names of the subsystems to the labels. The characters '.' and ':' are reserved and cannot be used in labels. To retrieve event data information use aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))). PPPPaaaaggggeeee 2222 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) AL_NO_OP (no type, get/set) The ALpv structure associated with this parameter is ignored. This effectively allows a program to "comment out" individual parameter/value pairs in a larger list without restructuring the list. AL_PARAMS (set of enum, query) Returns the set of parameters supported by this resource. SSSSYYYYSSSSTTTTEEEEMMMM PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS Each computer has a single system resource, with a fixed resource ID of AL_SYSTEM, representing global parameters of the audio software. The following parameters apply to the system resource. AL_MAX_PORTS (32-bit integer, get only) The maximum number of audio ports that can be simultaneously open on the system. AL_UNUSED_PORTS (32-bit integer, get only) The number of unused ports on the system. AL_MAX_SETSIZE (32-bit integer, get only) The maximum number of elements used by any set-valued parameter across the system. AL_DEFAULT_INPUT (resource, get/set/query/events) The current default input device for the system. The resource supplied must be a device. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss on this parameter will return the set of available input devices. AL_DEFAULT_OUTPUT (resource, get/set/query/events) The current default output device for the system. The resource supplied must be a device. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss on this parameter will return the set of available output devices. AL_DEVICES (set of resources, query only) The set of devices available on the system. AL_PORTS (set of resources, query/events: ALsetChangeInfo *) The set of ports currently in use. Creation or deletion of audio ports will generate events. To retrieve the event value data, use aaaallllGGGGeeeettttEEEEvvvveeeennnnttttDDDDaaaattttaaaa((((3333ddddmmmm)))). This function returns a void pointer to an ALsetChangeInfo struct: typedef struct _ALsetChangeInfo { ALvalue val; /* value of set element */ int total; /* total number of elements */ int pchange;/* delta ( +1 or -1) */ }ALsetChangeInfo; PPPPaaaaggggeeee 3333 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) The structure consists of val, the inserted or deleted set element; total, the new number of elements in the set; and delta, indicating the change in number of elements. AL_CONNECTIONS (set of resources, query/events: ALsetChangeInfo) The set of connections currently in use. Events will get generated as connections (or disconnections) are made to devices in the audio system. To retrieve the event value data use aaaallllGGGGeeeettttEEEEvvvveeeennnnttttDDDDaaaattttaaaa((((3333ddddmmmm)))). This function returns a void pointer to an ALsetChangeInfo struct. Refer to AL_PORTS for more information. The set of connections currently in use. AL_TYPE (32-bit integer, get only) Returns AL_SYSTEM_TYPE. DDDDEEEEVVVVIIIICCCCEEEE PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS An audio device is the top level of control for an input or output audio data stream. It is the place to which applications connect their ports to perform input or output. Each device has a cccclllloooocccckkkk----ggggeeeennnneeeerrrraaaattttoooorrrr to provide it with a sample-rate, and potentially a number of _i_n_t_e_r_f_a_c_e_s, each of which corresponds with a physical audio jack on the system. A device will accept parameters for the clock-generator and interfaces it is currently using. AL_CHANNELS (32-bit integer, get/set/query/events) The number of channels supported by the device. Some devices may support variable numbers of channels. AL_INTERFACE (resource, get/set/query/events on input devices; query only for output devices) For input devices, this is the interface (input source) currently in use. Input devices can use only one interface at a time, and typically support setting AL_INTERFACE. Output devices usually drive all available interfaces simultaneously; in this case, they will not support setting AL_INTERFACE, and will always return a value of AL_ALL_INTERFACES for this parameter. However, a few output devices share interfaces with other devices, and therefore allow setting of AL_INTERFACE. Use the _o_p_e_r_a_t_i_o_n_s field of aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm)))) to determine if AL_INTERFACE is settable on a particular device. The interface can be specified as a specific resource or by type (for example, AL_MIC_IF_TYPE to indicate a microphone interface). If the interface is given by type, the AL will choose an appropriate interface of the given type. PPPPaaaaggggeeee 4444 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))) returns the set of interfaces available to the device. AL_CLOCK_GEN (resource, get/set/query/events) The clock-generator this device is using to provide its sample-rate. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))) returns the set of clock-generators available to the device. AL_TYPE (32-bit integer, get only) The type of the device. Input devices will return some subtype of AL_INPUT_DEVICE_TYPE; output devices will return some subtype of AL_OUTPUT_DEVICE_TYPE. Use aaaallllIIIIssssSSSSuuuubbbbttttyyyyppppeeee((((3333ddddmmmm)))) to determine if one type is a subtype of another. AL_CONNECT (ALconnectionInfo*, events only: ALconnectionInfo) A connection involving the device occurred. To retrieve the event value data, use aaaallllGGGGeeeettttEEEEvvvveeeennnnttttDDDDaaaattttaaaa((((3333ddddmmmm)))). This function returns a void pointer to an ALconnectionInfo struct. The struct contains the id for the source resource, destination resource and connection resource. It is defined as: typedef struct _ALconnectionInfo { int source; int dest; int connection; } ALconnectionInfo; AL_DISCONNECT (ALconnectionInfo*, events only: ALconnectionInfo) A disconnect involving the device occurred. To retrieve the event information data use: aaaallllGGGGeeeettttEEEEvvvveeeennnnttttDDDDaaaattttaaaa((((3333ddddmmmm)))). This function returns a void pointer to al ALconnectionInfo. Refer to AL_CONNECT for more information. AL_SUBCODE_FORMAT (set of enum, query) The set of subcode data formats supported by the device. Values can be AL_AES_CHANNEL_STATUS, AL_AES_USER, AL_AES_VALIDITY. Subcode data streams describe distinct channels of continuous non-audio data that are inherently associated with a digital audio stream. AL_SUBCODE_FRAMESIZE (int, get only) If supported, indicates the number of bytes into which a single channel of subcode data will fit. This value is often used in conjunction with AL_SUBCODE_CHANNELS to determine sizing for memory allocation. For AES subcode, this value is 24, as defined by the IEC958/AES3 specifications for the transmission of digital audio signals. For ADAT subcode, this value is 4. PPPPaaaaggggeeee 5555 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) AL_SUBCODE_CHANNELS (int, get only) If supported, the number of subcode channels supported by a device for all subcode formats. This value when multiplied by the value provided by AL_SUBCODE_FRAMESIZE gives the size, in bytes of an entire multi-channel frame of subcode data. AL_INTERVAL (int, get only) If supported, indicates the number of audio frames required for the complete transmission of one multi- channel frame of subcode data. AL_AES_CHANNEL_STATUS, AL_AES_USER, AL_AES_VALIDITY (vector of bytes, get/set) These parameters, if supported, provide a means for a quick get or set of subcode data. They are not intended for real-time use. For input devices, these parameters are get-only and the returned vector of bytes is most recently captured full multi-channel subcode frame corresponding to the subcode data format parameter. For output devices, these parameters may have either get/set or get-only capabilities (depending on hardware -- use alGetParamInfo(3a) to check) and indicate the default multi-channel subcode frame to be transmitted. Subcode data bit ordering always puts subcode Byte 0, bit 0 in the most significant bit of Byte 0, thus allowing a big-endian bit shift operation to correspond to a subcode data time shift. See the IEC958 "Digital Audio Interface" and AES3-1992 "Serial Transmission Format For Two-Channel Linearly Represented Audio Data" specifications for the details on what the AES subcode data bits actually represent. IIIINNNNTTTTEEEERRRRFFFFAAAACCCCEEEE PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS Each device has a number of iiiinnnntttteeeerrrrffffaaaacccceeeessss, each of which corresponds to a physical audio jack or set of jacks on the machine. Input devices use one interface at a time. Output devices usually drive all their interfaces simultaneously with the same audio data. In some cases, an output device will only drive one interface at a time, usually because it is sharing an interface with another device. For example, the AESOut and ADATOut devices on some systems can share an optical interface, in which case each device drives only one interface at a time. AL_GAIN (vector of fixed-point values, get/set/events) The gain, in decibels (dB), per channel. Positive values represent gain; negative values represent attenuation. Interfaces without gain capability will return values of PPPPaaaaggggeeee 6666 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) 0 dB. The audio system will round unsupported gain values down to the nearest supported value. There are two special values for gain. An application can set a value of AL_NO_CHANGE on any channel, causing the gain value for that channel to remain unchanged. This value is supported on all interfaces. Also, the special value of AL_NEG_INFINITY corresponds to a gain of negative infinity decibels (mute). AL_NEG_INFINITY is only supported on some interfaces. To determine the gain range for an interface, and whether or not it supports AL_NEG_INFINITY, use the aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm)))) call. This returns an ALparamInfo structure for the AL_GAIN parameter on a particular interface. The mmmmiiiinnnn and mmmmaaaaxxxx fields of the ALparamInfo correspond to the minimum and maximum finite gain values, respectively. If AL_NEG_INFINITY is supported, the AL_NEG_INFINITY_BIT will be set in the specialVals field. To obtain event data information use aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))). AL_MUTE (32-bit integer, get/set/events) If true, mutes an output interface. If false, the interface is unmuted. Some output interfaces may ignore this (e.g. most digital interfaces). This parameter does not affect the value of the AL_GAIN parameter. An application which desires the "true" gain of the interface should look at both AL_GAIN and AL_MUTE. AL_WORDSIZE (32-bit integer, get/set/query/events) The number of significant bits on the interface. Though the AL will accept or produce 8-,16-, and 24-bit data with any interface, different interfaces will have differing numbers of significant bits. For example, most digital interfaces have 24 significant bits, while most analog interfaces have 16 or 18. AL_CHANNELS (32-bit integer, get/set/query/events) The number of significant channels supported by the interface. Note that this may differ from the number of channels supported by the device using the interface. For example, a stereo input device may have one mono microphone input and one stereo line-level input. In this case, the device returns AL_CHANNELS=2, and the interfaces return AL_CHANNELS=1 and AL_CHANNELS=2, respectively. AL_TYPE (32-bit integer, get) The type of the interface. All are subtypes of AL_INTERFACE_TYPE. Digital interfaces will be subtypes of PPPPaaaaggggeeee 7777 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) AL_DIGITAL_INTERFACE_TYPE; analog interfaces will be subtypes of AL_ANALOG_INTERFACE_TYPE. Refer to audio.h for a complete listing of interface types, and to aaaallllIIIIssssSSSSuuuubbbbttttyyyyppppeeee((((3333ddddmmmm)))) for information on subtypes in general. CCCCLLLLOOOOCCCCKKKK----GGGGEEEENNNNEEEERRRRAAAATTTTOOOORRRR PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS A clock-generator provides the sample-rate clock to an audio device. Each clock-generator takes a particular frequency reference, called a mmmmaaaasssstttteeeerrrr cccclllloooocccckkkk, and provides a precise fraction of that master clock to the audio device. For simplicity, an audio device will accept parameters on behalf of the clock-generator it uses. AL_RATE (fixed-point, get/set/events) The nominal sample-rate, in hertz. Unsupported values are rounded to the nearest supported value. When an application gets the value of AL_RATE, the AL will return the current nominal master clock rate times the current rate-fraction (see AL_RATE_FRACTION_*, below). In some cases, when the AL cannot determine the nominal sample-rate of the master clock, it will be unable to return a nominal sample-rate for the clock- generator. In these cases, the AL will return a negative value for AL_RATE. When an application sets the value of AL_RATE, the AL will set the value of the rate-fraction (see AL_RATE_FRACTION_*, below) based upon the nominal master clock rate. If the nominal master clock rate is unknown, the AL will _n_o_t change the sample-rate. Also, if the master clock rate changes, the AL will not automatically update the rate-fraction for a rate set by AL_RATE. For variable-rate master clocks, it is therefore usually better to use AL_RATE_FRACTION_* to set the sample-rate. For fixed-rate master clocks, such as crystals or video sources, AL_RATE and AL_RATE_FRACTION_* are equivalent representations. _N_o_t_e:In general, the master clock should be specified when the rate is changed. AL_RATE_FRACTION_N, AL_RATE_FRACTION_D (32-bit integer, get/set/events) The sample-rate, represented as an exact fraction (N/D) of the master clock. The value of (N/D) must lie between 0 and 1. If the exact fraction given cannot be supported, the AL will substitute a nearby fraction. If these two parameters are given in the same call to aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) or aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))), they will be set or acquired atomically. PPPPaaaaggggeeee 8888 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) In general, the master clock should be specified when the rate is changed. AL_MASTER_CLOCK (resource; get/set/query/events) The master clock from which this clock-generator derives its rate. The master clock can be specified as a specific resource or by type (for example, AL_CRYSTAL_MCLK_TYPE to indicate a crystal-based master clock). If the master clock is given by type, the AL will choose an appropriate master clock of the given type. aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))) returns the set of master clocks available to the clock-generator. AL_TYPE (int, get only) The type of the clock-generator. Returns AL_CLOCKGEN_TYPE. MMMMAAAASSSSTTTTEEEERRRR----CCCCLLLLOOOOCCCCKKKK PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS AL_RATE (fixed-point, get/events) The nominal rate of the master clock, in hertz. If the nominal rate is unknown, a negative value is returned. Some master clocks have variable sampling rates. An event will be generated if the rate of the master clock changes. AL_TYPE (int, get only) The type of the master clock. All are subtypes of AL_MCLK_TYPE. Fixed-rate master clocks, such as video- based clocks and crystal-based clocks, are subtypes of AL_FIXED_MCLK_TYPE. Variable-rate master clocks, such as AES- and ADAT-derived rates, are subtypes of AL_VARIABLE_MCLK_TYPE. AL_VIDEO_SYNC (enum, get/set/query/events) This parameter is only applicable on master clocks which are subtypes of AL_VIDEO_MCLK_TYPE. Valid values are AL_VID_INTERNAL and AL_VID_EXTERNAL, depending on whether the video timing signal is to come from an internal video sync bus or via an external video blackburst fed directly into the audio subsystem. CCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS A connection is a resource which moves audio data between an audio device and an audio port, or between two audio devices. See the man page for aaaallllCCCCoooonnnnnnnneeeecccctttt((((3333ddddmmmm)))) for more information. AL_SOURCE (resource, get only) The source of the connection. PPPPaaaaggggeeee 9999 aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) AL_DEST (resource, get only) The destination of the connection. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS SSSSEEEEEEEE AAAALLLLSSSSOOOO alSetParams(3dm), alGetParams(3dm), alGetParamInfo(3dm), alQueryValues(3dm) PPPPaaaaggggeeee 11110000 
